IRIX 6.4 Applications 1997 August

home *** CD-ROM | disk | FTP | other *** search

/ IRIX 6.4 Applications 1997 August / SGI IRIX 6.4 Applications 1997 August.iso / dist / insight.idb / usr / share / Insight / xhelp / HELPDEV.txt.z / HELPDEV.txt

Wrap

Text File | 1997-07-30 | 41.3 KB | 1,090 lines

Table of Contents ----------------- * Overview * Integrating sgihelp Into Your Application * Including the Header File and Linking with the Library * Understanding Available Calls Initializing Communication Making a Request from Within an Application Invoking the Index Window for the Application * Constructing a Help Menu: A Suggested Structure * Enabling Help From an Application Pushbutton * Providing Context-Sensitive Help within an Application * A Sample Application * Overview of the Application Helpmap File * Explanation of the Application Helpmap File * Adding Widget Hierarchies To the Helpmap File * Writing the Online Help What is SGML? What is a DTD? Creating the File Using the Sample SGML Files * Preparing to Build the Online Help * Building the Online Help * Finding and Correcting Errors * Producing the Final Product Overview ---------- Many of Silicon Graphics' desktop applications now provide online help. This document describes how to use Silicon Graphics' online help system, SGIHelp, to deliver the online help for your product. It describes how to prepare the help and integrate it into your application. Integrating SGIHelp Into Your Application ----------------------------------------------------------- When you install the package, you receive two files that allow you to use the SGIHelp system within your application. File Description Installed In ------------- ------------------------------- --------------------- HelpBroker.h Include file for help protocol /usr/include/helpapi libhelpmsg.a Library file to link app with /usr/lib Table 1. Developer Files Both the library and include file were developed in "C", and can be used with either the C or C++ programming languages. Including the Header File and Linking with the Library ------------------------------------------------------ To include the header file in your application, add the following line where the SGIHelp API calls will be made: #include <helpapi/HelpBroker.h> To use the API to communicate with the SGIHelp XHELP server, you need to link with the library libhelpmsg.a, installed in /usr/lib. For example, to compile a file "hellohelp.c++" to produce the executable "hellohelp", you would enter: CC -o hellohelp hellohelp.c++ -lhelpmsg -lX11 Note: Linking with the library requires that you include the X-library, libX11. Understanding Available Calls to Communicate with the Help Server ----------------------------------------------------------------- This section documents the calls to the help server (SGIHelp) and the values of the parameters. All calls return 1 upon success, and 0 upon failure. All communication to the help server is based upon X/ICCCM. There are three available calls. Table 2 briefly describes the purpose of each call. Below the table, you see more detailed explanations. Call Use -------------- -------------------------------------- SGIHelpInit() initiates contact with the help server SGIHelpMsg() starts sgihelp and displays a specific help card SGIHelpIndexMsg() opens an Index window that lists all available help topics for the application Table 2. Help Server Commands Initializing Communication -------------------------- To communicate with the help server properly, you must use the call SGIHelpInit(). SGIHelpInit() does not start-up or communicate with the actual help server process; it does store some important information used for the additional calls described below. SGIHelpInit(Display *dsp, char *client, char *sep); dsp : The structure that serves as the connection to the X server; result of the XOpenDisplay() call. client : The client application classname. Use the name that is used to retrieve the application's app-defaults, and not just an internal object class name (although they could be the same). Same as used by XtAppInitialize(). sep : Separator character used by the application to separate the widget hierarchy when a context sensitive help request is made. At this time, it is required that you use the character ".". Sample Code: ----------- #include <X11/Xlib.h> #include <helpapi/HelpBroker.h> void main(int, char**) { /* default to the value of the DISPLAY environment var */ Display *display = XOpenDisplay(NULL); if( display ) { /* initialize the help server */ SGIHelpInit(display, "MyApp", "."); } ... Making a Request from Within an Application: ------------------------------------------- If a copy of the help server is not already running, SGIHelpIndexMsg() automatically starts the server if the application (sgihelp) is available. SGIHelpMsg (char *key, char *book, char *user_data); key : Tells the help server what information to render. In some cases, this could be the direct key from a help book the application uses, or it could be a widget hierarchy. If a widget hierarchy is passed, the help server looks in the application's helpmap file to find a mapping. If if doesn't find an exact match, it uses a fallback algorithm to determine which is the "closest" hierarchy found. See "The Application Helpmap File" for more information. book : Gives the name of the help "book" that contains the application's help information. If you set this to NULL or "*", the help server looks in the the application's helpmap file for the book name. In the latter case, a helpmap file must exist. See "The Application Helpmap File" for more information. user_data : Reserved for future use. All applications should set this field to NULL. Sample Code: ----------- #include <X11/Xlib.h> #include <helpapi/HelpBroker.h> void main(int, char**) { /* assume initialization of help server is complete */ /* * This call will render the section (card) with a key * of help_save_button (found in the "HelpId=" field). * It will look for this section in the book "MyAppHelp". */ SGIHelpMsg("help_save_button", "MyAppHelp", NULL); ... Invoking the Index Window for the Application: --------------------------------------------- This call causes the help server to look for the application's helpmap file, and invoke the Help Index window. The index presents a listing of all the help topics listed in the helpmap file. You must have a helpmap file for this call to work properly. See "The Application Helpmap File" for more information. SGIHelpIndexMsg (char *key, char *book); key : Set to NULL or "index". book : Reserved for future use. Set to NULL. Sample Code: ----------- #include <X11/Xlib.h> #include <helpapi/HelpBroker.h> void main(int, char**) { /* assume initialization of help server is complete */ /* * This call will look in the application's helpmap * file for a list of topics to display to the user in * sgihelp's index window. */ SGIHelpIndexMsg("index", NULL); ... o Constructing a Help Menu: A Suggested Structure ----------------------------------------------- If your application contains a menubar, you can include a Help pulll-down menu. This section describes a convention used by applications that are a part of the Indigo Magic User Environment. Note that these items are derived from the Motif 1.2 Style Guide (class 2). Below you see a sample structure for a Help menu: Click for Help Shift+F1 Overview -------------------------------- "list of topics" -------------------------------- Index Keys & Shortcuts -------------------------------- Product Information "Click for Help" Provides context-sensitive help. When a user chooses "Click for Help," the cursor turns into a "?". The user can move the cursor over an item/area of interest and click. Clicking the mouse button initiates communication with the help server; SGIHelp displays a help card. You, the developer, are responsible for writing code that tracks the cursor and interrogates the widget hierarchy. Somewhere, you need to make a mapping between what the user has clicked on, and the help card that's displayed. One option is to provide the mapping via the application helpmap file. See "The Application's Helpmap File." Another possibility is to use the "HelpId=" attribute in the help text. "Overview" Provides an overview of the window or application. "list of topics" Presents a list of task-oriented help topics that can be added to the menu. The entries can be listed in the application's defaults file, with a menu item/help_key structure, or can be read directly from the application's helpmap file. "Index" Displays a list of help topics for the application. You must have an application helpmap file if you use the call SGIHelpIndexMsg(). "Keys & Shortcuts" Displays a help card that contains the application's accelerator keys, keyboard shortcuts, etc... "Product Information" Produces a dialog box showing the name, version and any copyright information or other related data for this application. o Enabling Help From an Application Pushbutton -------------------------------------------- If your application doesn't contain a menubar, you can provide a Help button. This code sample displays how you can use the SGIHelp API to communicate with the sgihelp server from a pushbutton within your application. Sample Code: ----------- /* required include file for direct communication with help server #include <helpapi/HelpBroker.h> #include <X11/Xlib.h> ... /* initialize help server information */ SGIHelpInit(display, "MyWindowApp", "."); ... /* create help pushbutton for your window */ Widget helpB = XmCreatePushButton(parent, "helpB", NULL, 0); XtManageChild(helpB); XtAddCallback(helpB, XmNactivateCallback, (XtCallbackProc)helpCB, (XtPointer)NULL); ... /* help callback */ void helpCB(Widget w, XtPointer clientData, XtPointer callData) { /* * communicate with the help server; developer * may wish to pass the "key" in as part of the * callback's callData parameter... */ SGIHelpMsg("key", "book", NULL); } The "key" is described in "Available Calls to Communicate with the Help Server." It's found within the "book" that contains the application's help text, or in the application's helpmap file. The helpmap file provides a "level of indirection" between the help content and your code. Sending this "key" to the help server causes the server to render the card that contains the "key" as it's "HelpId=" attribute. o Providing Context-Sensitive Help within an Application ------------------------------------------------------ You may want to provide context sensitive help from within your application. To do so, you need to write code that tracks the cursor and interrogates the widget hierarchy. Additionally, you need to make a mapping between what the user has clicked on, and the help card that's displayed. One option is to provide the mapping via the application helpmap file. See "The Application's Helpmap File." Another possibility is to use the "HelpId=" attribute in the help text. This code sample assumes you are using X/Motif, and is provided as an example. Note that some areas, such as menu creation, are missing. See XmTrackingLocate(3X) for further information. Sample Code: ----------- /* required include file for direct communication with help server #include <helpapi/HelpBroker.h> ... /* create menu; set menu to be the "help menu" for this window */ createHelpMenu(); XtVaSetValues(parent, XmNmenuHelpWidget, _helpMenuPaneWidget, NULL); ... /* add callback for menu item that triggers context-sensitive mode */ XtAddCallback(helpOnContextWidget, XmNactivateCallback, (XtCallbackProc)onContextCB, (XtPointer)NULL); ... void onContextCB(Widget wid, XtPointer clientData, XtPointer callData) { static Cursor cursor = NULL; static char path[MAX_STR], tmp[MAX_STR]; Widget shell, w, result; strcpy(path, ""); strcpy(tmp, ""); /* create a question-mark cursor */ if(!cursor) cursor = XCreateFontCursor(display, XC_question_arrow); XmUpdateDisplay(mainWindowWidget); /* get the top-level shell for the window */ shell = mainWindowWidget; while (shell && !XtIsShell(shell)) { shell = XtParent(shell); } /* * modal interface for selection of a component; * returns the widget or gadget that contains the pointer */ result = XmTrackingLocate(shell, cursor, FALSE); if( result ) { w = result; /* get the widget hierarchy; separate with a '.'; * this also puts them in top-down vs bottom-up order. */ do { if( XtName(w) ) { strcpy(path, XtName(w)); if( strlen(tmp) > 0 ) { strcat(path, "."); strcat(path, tmp); } strcpy(tmp, path); } w = XtParent(w); } while (w != NULL && w != shell); /* * send msg to the help server-widget hierarchy; * OR * provide a mapping to produce the key to be used */ if( strlen(path) > 0 ) SGIHelpMsg(path, "MyAppBook", NULL); } } o A Sample Application -------------------- Below you see a simple command-line program that accepts parameters and passes them on to the help server. We created this program to test the SGIHelp server; however, it could probably be used (with some modifications) to provide a true shell/Unix command help facility. Sample Code (helpcmd.c): ----------------------- #include <X11/Xlib.h> #include <getopt.h> #include <ctype.h> #include <string.h> extern char *optarg; extern int optind,opterr; static void usage(); /* required include file for direct communication with help server #include <helpapi/HelpBroker.h> void main ( int argc, char **argv ) { Display *display; int c,c2,i; char app[80], cmd[80], bk[80], key[1024]; /* set defaults */ strcpy(app, ""); strcpy(key, ""); strcpy(bk, "*"); strcpy(cmd, "view"); /* user needs to specify something */ if (argc <= 1) { usage(); exit(0); } /* default to the value of the DISPLAY environment var */ display = XOpenDisplay(NULL); while ((c = getopt(argc,argv,"a:k:b:c:h")) != -1) { switch (c) { case 'a': /* app; will use helpmap if available */ strcpy(app, optarg); break; case 'k': /* help key; from "HelpId=" attribute */ strcpy(key, optarg); break; case 'b': /* book containing help text */ strcpy(bk, optarg); break; case 'c': /* render a card, or display index */ strcpy(cmd, optarg); /* convert command string to lower-case*/ for(i=0; i<strlen(cmd); i++) { c2=tolower(cmd[i]); cmd[i] = c2; } if( strcmp(cmd, "view") != 0 && strcmp(cmd, "index") != 0 ) { usage(); exit(1); } break; case 'h': default: usage(); exit(0); break; } } /* initialize help and send a msg */ SGIHelpInit(display, app, "."); if( strcmp(cmd, "view") == 0 ) SGIHelpMsg(key, bk, NULL); else SGIHelpIndexMsg(app, NULL); /* cleanup */ XCloseDisplay(display); exit(0); } static void usage() { printf("\nhelpcmd -a [app_classname] -k [key] -c [cmd] -b [book]\n"); printf("\nwhere:\n\t- app_classname\n"); printf("\t- key is the key for the card you wish to display\n"); printf("\t- cmd is either \"view\" or \"index\"\n"); printf("\t- book is the help book to use\n"); } o Overview of the Application Helpmap File ---------------------------------------- Providing a helpmap file is not essential; it is recommended, however, especially if you're planning to provide context-sensitive help for your application. You can use the helpmap file to: * generate the list of items you want to appear in the Help index for your application. * construct the "list of topics" for the Help menu. (See "Constructing a Help Menu: A Suggested Structure" for details on the list of topics.) To get this behavior, you need to write code that parses the helpmap file and extracts these entries. * provide a level of indirection between the help content and your code. Rather than embedding the mapping scheme within your application's code, you can place the mapping in the helpmap file. The SGIHelp help server accesses the helpmap file directly. For example, you can implement context-sensitive help, and pass in the concatenated widget hierarchy as the "key" parameter of the SGIHelpMsg() API call. When the SGIHelp process receives the widget string, it examines the application's helpmap file, reading in all mappings that have been provided. It parses the strings, and looks for an "exact" match. If it finds a match, it uses the "book" name (field 2 in the helpmap file) and "key" (field 5 in the helpmap file) to find and display the correct topic. If it doesn't find an "exact" match, it uses a fallback algorithm to find the "closest" match. Here's an example of how the fallback algorithm works. Suppose your application includes a row or set of buttons. When the user asks for help on a button, you pass that widget string to SGIHelp. If the widget string is *not* found in the mappings, the last widget is dropped off the string (in this case, the widget ID for the button itself). The new string is compared to all available mappings. This loop continues until *something* is found. At the very least, you should fall back to an "Overview" card. o Explanation of the Application Helpmap File ------------------------------------------- This section describes the format and naming convention for the helpmap file. It begins with a table, and ends with a description of each field in the helpmap file. Item Description ------- ----------------------------------------------------------- Format plain ASCII text Name the application class name, (which is passed as part of the SGIHelpInit() call)followed the the extension ".helpmap". For example, if the application class name is "MyApp," the helpmap file should be named "MyApp.helpmap." Installed in /usr/share/help Table 3. Helpmap conventions. Each line in the helpmap file contains six fields. The fields are separated by semi-colons. Below is a sample entry in a helpmap file, and a description of the fields. Entries in a helpmap file will be referred to as "help topic"'s in the following discussion. All fields are REQUIRED for each help topic. If a field does not have an entry for the title (see below), then set it to a blank space, " ". Sample entry from /usr/share/help/Fm.helpmap: -------------------------------------------- 0;IRISEssentials;The Find an Icon Window;0;fetch_help;Fm.Fetch ^ ^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^ ^ ^^^^^^^^^^ ^^^^^^^^ 1 2 3 4 5 6 Description of Fields: --------------------- 1 A number that indicates what type of help topic it is. 0 - a context-sensitive point 1 - the Overview card for the application 2 - a Task-oriented entry that could show up in a Help menu 3 - the card that talks about Keys and Shortcuts 4 - reserved for future use You can use these settings to construct a potential "list of topics" within a Help menu. See "A Suggested Application Help Menu Structure". You can also use these numbers to determine which menu items should be inactive (grayed-out). For example, suppose the Help menu contains an entry for "Keys and Shortcuts", but there is no entry in the application helpmap file of type "3". You should dynamically omit that menu item, OR make that item inactive (grayed). 2 The name of the "book" that contains this help topic. Note that help topics can reside in different books. Each INDIVIDUAL help topic can point to only one help book. 3 The name/title of the help topic. This could appear in a Help menu, if you parse the helpmap file to construct the "list of topics" on the Help menu. 4 A number that determines whether the topic is a main topic or a sub-topic. If all the entries are main topics, set the value to "0". To denote a sub-topic, set the value to "1". The entry will be a sub-topic of the item marked "0" that precedes it in the helpmap file. This produces an expandable/collapsible outline for the Help Index window. It can also be used to construct a "roll-over" sub-menu as part of a Help menu. To get this behavior, you need to parse the helpmap file to construct the "list of topics" in the Help menu. 5 The help key, which will be used to render the specific card for this help topic. This is the same key found in the help book or in the "HelpId=" attribute for the given card. 6-n A list of widgets, primarily used for context-sensitive help. Note that this field can contain multiple entries, all delimited by semi-colons. In this way, you can associate different areas with the same help cards/topics. o Adding Widget Hierarchies To the Helpmap File --------------------------------------------- At least *one* widget hierarchy must accompany every point in the application helpmap file. That one (default) point should be set to "<application_classname>.<window_classname>". In our example from the previous section, that happens to be "Fm.Fetch"; where "Fm" is the application classname, and "Fetch" is the window classname (top-level shell). Note that the application classname must ALWAYS be the first component of a widget hierarchy string. All widget id's within the string should be delimited by a "." (period). Widget hiearchies can be as fine-grained as you wish to make them. A fall-back algorithm is in place (to go to the closest available "entry") when the user clicks on a widget in context-sensitive help mode. To get a sample widget hiearchy (help message) from an application, you can run the SGIHelp help server process in debug mode. Before doing this, you need to add the SGIHelp API call, SGIHelpMsg(), to your application and implement context-sensitive help. Make sure that you send a widget hierarchy string for the "key" parameter in the SGIHelpMsg() call. (See "Providing Context-Sensitive Help within an Application" and "Understanding Available Calls" for details on this call.) Example ------- 1) Bring up a shell 2) Make sure the SGIHelp help server process isn't running: % /etc/killall sgihelp 3) Type the following to make the SGIHelp help server process run in the foreground in debug mode: % /usr/sbin/sgihelp -f -debug 4) Run your application, and then choose "Click for Help" from the help menu. The cursor should change into a "?" (or whatever you've implemented for context sensitive help). 5) Click on a widget, or area of the application. 6) Check the shell from which sgihelp is being run. You should see a line such as: REQUEST= client="Overview" command="view" book="" keyvalue="DesksOverview.MainView.Frame.viewport.Bboard" separator="." user_data="" The "keyvalue" field is the one to notice. It contains the widget hierarchy that you can add to the helpmap file. Remember to add the application classname to the front of the string. For our example above, the full widget hierarchy string to be added to a helpmap entry would be: Overview.DesksOverview.MainView.Frame.viewport.Bboard Writing the Online Help ----------------------- This section describes how you prepare the online help document. It provides an explanation of the standard format you must use, as well as the steps you take to actually prepare the file. What is SGML? ------------- SGML stands for Standard Generalized Markup Language. Silicon Graphics has adopted SGML as the standard format for its online books and help. As such, when you write the online help for your product, you need to embed SGML tags. See the file /usr/share/Insight/XHELP/samples/sampleDoc/sample.sgm as an example. Notice the tags surrounded by angle brackets (<>). These tags describe how each item fits into the structure of the overall document. For example, a paragraph might be tagged as a list item, and a word within that paragraph may be tagged as a command. For a more complete understanding of SGML, see the bibliography at the end of this document. It lists several of the many books on SGML. What Is a DTD? -------------- DTD stands for Document Type Definition. It is a text file that outlines the tagging rules for your online documentation. In other words, it specifies which SGML tags are allowed, and in what combination or sequence. The file /usr/share/Insight/XHELP/dtd/XHELP.dtd lists the legal structure for your online help. Creating the File ------------------ All of the online help for your product is stored in one text file. To get started: 1. Create a new directory for the online help; then change to this directory. 2. Create a text file and name the file TITLE.sgm, where TITLE is one word that identifies the online help. 3. Begin writing the online help. Using the Sample SGML Files --------------------------- Before beginning to embed the SGML tags, see the file /usr/share/Insight/XHELP/samples/sampleDoc/sample.sgm. You can model your online help after this example. To compare this SGML file to the online help it produces, you can build two help files. To do so: 1. Change to a directory in which you want to build the sample help book. 2. Copy the necessary directories and files by typing: cp -r /usr/share/Insight/XHELP/samples . 3. Type: cd samples/sampleDoc 4. Build the file sample.sgm by typing: make help To view this file, type: iiv -b . -v sample 5. cd ../exampleApp 6. Build the file exampleAppXmHelp.sgm by typing: make help 7. To view this file, type: iiv -b . - v exampleAppXmHelp Preparing to Build the Online Help ---------------------------------- The online help must be built, just as a program must be compiled. When you build the online help, you transform the raw SGML file into a viewable, online document. To get started, you need to create two files--a Makefile and a spec file. You use the Makefile to specify the following: - the name of file that contains the online help - the name you want to assign to the help book - the version number of the product You use the spec file to define the title of your product, the official release and version numbers, and other information that is used when you create the final images. To create these files: 1. Move to the directory that contains the online help file. 3. Copy /usr/share/Insight/XHELP/templates/Makefile_xhelp by typing: cp /usr/share/Insight/XHELP/templates/Makefile_xhelp Makefile 4. Copy /usr/share/Insight/XHELP/templates/spec_xhelp by typing: cp /usr/share/Insight/XHELP/templates/spec_xhelp spec At this point, the directory should contain two additional files: Makefile and spec. 5. Edit the Makefile. - Next to the label TITLE, type the name of the file that contains the online help. - Next to the label FULL_TITLE, type the name you want to assign to the help book. This name can contain several words, and is used only if you decide to display the help as a "book" on the Insight bookshelf. - Next to the label VERSION, type the version number for the product. - Next to the label HIDDEN, remove the comment character (#) if you want the online help to appear as a book on an Insight bookshelf. Change this if you want users to be able to browse the help information via Insight, and not just from within your application. 6. Edit the spec file. - Replace the string ${RELEASE} with the release number for the product. This should match what you've entered in the Makefile for the VERSION. - Replace the string <ProductName> with a one-word name for the product. - Replace the string <Shortname> with the TITLE you specified in the Makefile. - Replace the string <SHORTNAME> with the TITLE you specified in the Makefile. Capitalize all letters. - Replace the string <SHORTNAME_HELP> with the TITLE followed by by the "_HELP". - Replace the string <Book title> with the FULL_TITLE you specified in the Makefile. Building the Online Help ------------------------ Once you have written the online help, and done the preparation described in "Preparing to Build the Online Help," you can build and view the online help. To do so: 1. Go to the directory that contains the online help files. 2. Type: make help If the help is formatted properly, the online help will build and you should see these files in the directory: If the SGML file contains errors, you will see them displayed in the shell window. See "Finding and Correcting Errors" for details. 3. View the book by typing: iiv -b . -v <TITLE> Where <TITLE> is the value of TITLE from the Makefile. Finding and Correcting Errors ----------------------------- The SGML tags come in pairs. Each pair contains an opening tag and a closing tag, and the tag applies to everything between the opening tag and the closing tag. If you use these tags incorrectly, you will get error messages while you're building the help file. The most common errors are the result of misspelled tag names, mismatched end tags, or tags used out of sequence. This section lists some sample error messages. SAMPLE 1 mkhelperror: not authorized to add tag 'PAR', ignoring content. This error appears if you specify an invalid tag. In this case, the invalid tag is "PAR." The valid tag name is "PARA." SAMPLE 2 mkhelperror: Start-tag for 'HELPLABEL' is not valid in this context. mkhelp Location: Line 37 of entity '#DOCUMENT' Context: 'hor point for the link syntax.</>&#RS;</HelpTopic>&#RS;&#RS;<Helplabel>'... '<Anchor Id="AI003">Using Notes, Warnings or Tips Within a P' FQGI: DOCHELP This error message occurs when the parser sees a tag it isn't expecting. In this case it found a HELPLABEL that was not preceded by a HELPTOPIC start tag. The error message specifies the line number of the error (37), the context in the file, and the Fully Qualified Generic Identifier (FQGI) of the context. You can probably ignore the FQGI; it describes where the error occurs within the SGML structure. SAMPLE 3 mkhelperror: No 'WARNING' is open, so an end-tag for it is not valid. The last one was closed at line 46. mkhelp Location: Line 46 of entity '#DOCUMENT' Context: '<warning>Missing open para. This is a warning.</></warning>'... '&#RS;<note><para>For your information, this is a note.</></note' FQGI: DOCHELP,DESCRIPTION,PARA,PARA This message can occur if you close items with the generic end tag, </>. In this case, the </> closes the <warning> because the start tag for <para> is missing. This may occur if you leave out a start tag or accidentally spell it incorrectly. If you want additional information about the errors, use the command "make verify". It produces a more detailed error log. Producing the Final Product ---------------------------- After you've finished writing and building your online help, you need to package it so that users can install it with the rest of your product. To do so: 1. Go to the directory that contains the online help. 2. Type: make images. This produces a directory called "images." This directory contains all of the files you need to let users install the help with your product. They're prepared so users can install them via "inst," Silicon Graphics' software installation program. If you use a different method for installing software, do one of the following. - If users install your product using the "tar" command, have them use tar to copy the online help images as well. After copying the images, the user needs to type: inst -af <inst_product>, where inst_product is the location of the images. - If you've created a script, enhance the script so that it extracts all of the help images onto disk, and then invokes the command "inst -af <inst_product>", where inst_product is the location of the images. Bibliography of SGML References -------------------------------- <1> *SoftQuad, Inc. The SGML Primer. SoftQuad's Quick Reference Guide to the Essentials of the Standard: The SGML Needed for Reading a DTD and Marked-up Documents and Discussing them Reasonably. Version 2.0. Toronto: SoftQuad Inc., May 1991. 36 pages. Available from SoftQuad Inc.; 56 Aberfoyle Crescent, Suite 810; Toronto, Ontario; Canada M8X 2W4; TEL: +1 (416) 239- 4801; FAX: +1 (416) 239-7105. <2> Bryan, Martin. SGML: An Author's Guide to the Standard Generalized Markup Language. Wokingham/Reading/New York: Addison-Wesley, 1988. ISBN: 0-201-17535-5 (pbk); LC CALL NO: QA76.73.S44 B79 1988. 380 pages. A highly detailed and useful manual explaining and illustrating features of ISO 8879. The book: (1) shows how to analyse the inherent structure of a document; (2) illustrates a wide variety of markup tags; (3) shows how to design your own tag set; (4) is copiously illustrated with practical examples; (5) covers the full range of SGML features. Technical and non-technical authors, publishers, typesetters and users of desktop publishing systems will find this book a valuable tutorial on the use of SGML and a comprehensive reference to the standard. It assumes no prior knowledge of computing or typography on the part of its readers. <3> Goldfarb, Charles F. The SGML Handbook. Edited and with a foreword by Yuri Rubinsky. Oxford: Oxford University Press, 1990. ISBN: 0-19-853737-1. 688 pages. This volume contains the full annotated text of ISO 8879 (with amendments), authored by IBM Senior Systems Analyst and acknowledged "father of SGML," Charles Goldfarb. The book was itself produced from SGML input using a DTD which is a variation of the "ISO.general" sample DTD included in the annexes to ISO 8879. The SGML Handbook includes: (1) the up-to-date amended full text of ISO 8879, extensively annotated, cross-referenced, and indexed (2) a detailed structured overview of SGML, covering every concept (3) additional tutorial and reference material (4) a unique "push- button access system" that provides paper hypertext links between the standard, annotations, overview, and tutorials. <4> Herwijnen, Eric van. Practical SGML. Dordrecht/Hingham, MA: Wolters Kluwer Academic Publishers. 200 pages. ISBN: 0-7923- 0635-X. The book is designed as a "practical SGML survival-kit for SGML users (especially authors) rather than developers," and itself constitutes an experiment in SGML publishing. The book provides a practical and painless introduction to the essentials of SGML, and an overview of some SGML applications. See the reviews by (1) Carol Van Ess-Dykema in Computational Linguistics 17/1 (March 1991) 110-116, and (2) Deborah A. Lapeyre in <TAG> 16 (October 1990) 12-14. <5> Smith, Joan M.; Stutely, Robert S. SGML: The Users' Guide to ISO 8879. Chichester/New York: Ellis Horwood/Halsted, 1988. 173 pages. ISBN: 0-7458-0221-4 (Ellis Horwood) and ISBN: 0-470- 21126-1 (Halsted). LC CALL NO: QA76.73.S44 S44 1988. The book (1) supplies a list of some 200 syntax productions, in numerical and alphabetical sequence; (2) gives a combined abbreviation list; (3) includes highly useful subject indices to ISO 8879 and its annexes (4) supplies graphic representations for the ISO 8879 character entities; (5) lists SGML keywords and reserved names. An overview of the book may be found in the SGML Users' Group Newsletter 9 (August 1988) 9. <6> ISO 8879:1986. Information Processing -- Text and Office Systems -- Standard Generalized Markup Language (SGML). International Organization for Standardization. Ref. No. ISO 8879:1986 (E). Geneva/New York, 1986. A subset of SGML became a US FIPS (Federal Information Processing Standard) in 1988. The British Standards Institution adopted SGML as a national standard (BS 6868) in 1987, and in 1989 SGML was adopted by the CEN/CENELEC Standards Committees as a European standard, #28879. Australia has dual numbered versions of ISO 8879 SGML and ISO 9069 SDIF (AS 3514 - SGML 1987; AS 3649 - 1990 SDIF). A one-page NTIS technical note on ISO 8879 as a US FIPS document, FIPS-PUB-152, provides the following abstract for ISO 8879: Abstract "This citation summarizes a one-page announcement of technology available for utilization. A Federal Information Processing Standard (FIPS) recently approved by the Secretary of Commerce should help federal agencies improve their communications with publishing organizations. (FIPS are developed by NIST for use by the federal government.) The new standard, called Standard Generalized Markup Language (SGML), provides a common way for defining markup languages so documents can be transferred from author to publisher in a standardized format. By providing a coherent and unambiguous syntax for describing the elements within a document, SGML makes it easier to move unformatted textual data among different installations and processing systems. Developed by the International Organization for Standardization (ISO) and the American National Standards Institute (ANSI) with assistance from NIST, the SGML standard is already being used by the Computer-Aided Acquisition and Logistics Support (CALS) program of the Department of Defense to develop a military specification. NIST is providing technical support for the CALS program. In addition, NIST has developed the first set of conformance tests for SGML; ISO and ANSI are considering using these tests for their own test suites." See "Publishing Standard Allows for the Transfer of Documents from Author to Publisher," NTIS Tech Note, 081914000; National Bureau of Standards, Gaithersburg, MD; May 1989. The SGML standard is now (1991) in the process of its first five-year review. National member bodies of ISO and other entities are submitting revision statements to the ISO/IEC JTC1/SC18/WG8 for review. See, for example, statements by ANSI X3VI.8 and the SGML Users' Group, printed in the SGML Users' Group Newsletter 20 (September 1991) 20. For other possible addenda and changes to 8879, see "Recommendations for a Possible Revision of ISO 8879. ISO/IEC JTC1/SC18/WG8 N931 [Part I]," <TAG> 12 (December 1989) 6-8 and "Recommendations for a Possible Revision of ISO 8879. Part II. ISO/IEC JTC1/SC18/WG8 N931," <TAG> 13 (February 1990) 12-15; "Additional Recommendations for a Possible Revision of ISO 8879 - Information Processing - Text and Office Systems (ISO/IEC JTC1/SC18/WG8 N1013," <TAG> 15 (August, 1990) 12-14. Balloting of 18 countries' national standards bodies (from 25) based upon review of the standard between November 15, 1990 and February 28, 1991 resulted in general confirmation of ISO 8879, with six requests for revision. WG8 will continue to review ISO 8879 in light of the comments and recommendations for revision, but the standard is thus confirmed through 1996. See details in "Replies on Review of ISO 8879 (SGML," EPSIG News 4/4 (December 1991) 8. <7> ISO 8879:1986 / A1:1988 (E). Information Processing -- Text and Office Systems -- Standard Generalized Markup Language (SGML), Amendment 1. Published 1988-07-01. Geneva: International Organization for Standardization, 1988.